%
% The FEEL manual sources.
%
% $Id: feel.tex,v 2.0 1992/03/15 17:20:05 pab Exp pab $
%
% $Log: feel.tex,v $
% Revision 2.0  1992/03/15  17:20:05  pab
% new version
%
% 
% Revision 1.8  90/11/07  21:34:31  kjp
% Make configurations, start up customisations, !> and futures.
%

\documentstyle[fullpage,a4,eulisp]{article}
\def\Version{0.89}
\makeindex
\title{FEEL: An Implementation of E{\large U}L{\large ISP}\\
Version \Version}
\author{
Concurrent Processing Research Group\\ School of Mathematical
Sciences\\ University of Bath, United Kingdom\\ E-mail: {\tt
eulisp@maths.bath.ac.uk} }
\newcommand{\standard}[1]{\entry{#1}{\level}}
\newcommand{\accessor}[1]{\entry{#1}{\level accessor}}
\newcommand{\constructor}[1]{\entry{#1}{\level constructor}}
\newcommand{\updator}[1]{\entry{#1}{\level updator}}
\newcommand{\gen}[1]{\entry{#1}{\level\ generic}}
\newcommand{\mtd}[1]{\entry{#1}{\level method}}
\newcommand{\comment}[1]{}
\newcommand{\classname}[1]{{\tt <#1>}}
\newcommand{\filename}[1]{{\tt #1}}
\begin{document}
\maketitle\thispagestyle{empty}
\def\level{Feel}

\begin{abstract}
  This document describes an implementation of \eulisp\ called \feel.
  The primary reference for \eulisp\ is the \eulisp\ definition.  In
  this document, the environmental operations provided in \feel, but
  which are not part of the \eulisp\ language, are described in
  detail, and examples on the use of some eulisp features are
  provided.
\end{abstract}

\section{Getting further information}
Information about \eulisp\ and a copy of the \feel\ implementation are
all available from the {\tt eudist} mail server at the University of
Bath.  Here is a summary of the services provided\footnote{These
addresses may not work. The authors of this document are {\tt
pab,jap@maths.bath.ac.uk}}:

\medskip
\begin{tabular}{|l|l|p{7cm}|}\hline
  Address & Subject Field & Effect \\\hline\hline {\tt
  eudist@maths.bath.ac.uk} & {\tt feel} & Distributes the current
  release of \feel.  Each file will be sent individually in a
  uuencoded, compressed format.
  \\\hline {\tt eudist@maths.bath.ac.uk} & {\tt definition} &
  Distributes the current release of the \eulisp\ definition,
  rationale and commentary in {\tt .dvi} format.  Each file will be
  sent individually in a uuencoded, compressed format.
  \\\hline {\tt eubug@maths.bath.ac.uk} & something germane & Please
  provide body too!  This mail-id is for reporting bugs in the
  definition or in \feel.
  \\\hline
\end{tabular}

\section{Making FEEL}
The kind of \feel\ system you can make depends on the combined
capabilities of your operating system and processor.  \feel\ has been
developed in a solely Unix environment and this has considerably
warped its view of the world.  So far, \feel\ has only been ported to
different versions of Unix.  A particular feature of \eulisp\ is
support for multiple threads of control.  Whether these do actually
execute concurrently depends on the host system, but, in principle, it
should be possible to develop a program using threads on one
system---perhaps a uni-processor simulating concurrency---and later
execute the same program on a multi-processor or a distributed
processor to achieve the same net result.

Broadly speaking, \feel\ can be made in any of three main
configurations \dots

\begin{description}
  
\item[Generic] Under the ``any'' machine configuration, \feel\
  attempts to be a fully portable ANSI C program. Because there is no
  reliably portable method of implementing threads in C, the thread
  operations in this mode are not available and only a serial version of
  \eulisp\ remains. This mode is most suitable for getting started
  quickly and also the most sensible place to begin for porting to new
  architectures or operating systems. Memory use is minimised which may
  benifit smaller machines such as PCs or any system where memory is at
  a premium.
  
\item[BSD] This (badly named) configuration mode requires that a stack
  switching operation be available for \feel\ to use. Given this code
  (typically a few lines of the local assembler), the thread operations
  become available with the limitation that only one thread is run at a
  time.  This mode allows programs to be written in terms of threads
  which may later be run in parallel without alteration. This mode is
  most useful for allowing the developing multi-threaded applications
  under unsupportive operating systems such as BSD 4.2 or 4.3.
  
\item[System V] This configuration requires that stack switching code
  be available along with the standard System V shared memory
  manipulation primitives. Given these things \feel\ becomes a truly
  parallel multi-threaded system using the following model: on start-up
  a piece of shared memory is allocated, then \feel\ forks as many times
  as there are physical processors in the host machine (this behaviour
  may be modified).  Each of these forked processes runs the \feel\
  scheduler, running threads from the pool in the shared heap.  Each
  such thread is run to conclusion---unless it yields control, in which
  case it will be returned to the pool. More processes may be forked
  than existing processors to simulate truly parallel operation on
  uniprocessor systems such as Suns running SunOS 4.1.
  
\end{description}

\section{The FEEL environment}

\feel\ uses the shell variable \verb?FEEL_LOAD_PATH? to load modules.  If
this variable is unset, then modules are sought in the directory in
which \feel\ was invoked and in a directory specified when the system
was built.  The value of \verb?FEEL_LOAD_PATH? is read at start-up and
converted to a list of strings of information in a processor-defined
format concerning the filesystems or disks or directories to be
searched when loading modules.  Modules are stored in files with the
extension {\tt .em}.

Similarly, the shell variable \verb|FEEL_INTF_PATH| is used to find
module interface files.  If the variable is unset, only the directory
in which \feel\ was invoked will be searched.  The value of
\verb|FEEL_INTF_PATH| is read at start-up and converted in a manner
analogous to that for \verb|FEEL_LOAD_PATH|.  Interfaces are stored in
files with the extension {\tt .i}.

\subsection{Getting in and out}
\feel\ is started by typing {\tt feel}, assuming correct paths and
installation.  To leave \feel\ type CNTL-D, or possibly {\tt !exit}
(see later section).

\subsection{Interacting with FEEL}

When \feel\ starts, the top-level is initially set to the {\tt user}
module\footnote{This can be changed by setting the environment
variable FEEL\_START\_MODULE}. This imports {\tt eulisp0}, and 
therefore contains most of the usual lisp functions. Most of the
module manipulation functionality is defined in the {\tt root} module.
The only operations defined in the {\tt root} module are those for
loading modules and entering modules (see below). The top-level prompt
provides information about which module is the current focus and the
history number of the command, for example:

\begin{verbatim}
eulisp:0:root!3>
\end{verbatim}

\noindent
signifies that the top-level is executing on thread {\tt 0}, the
current module focus is {\tt root} and that the command history index
of this line is {\tt 3}.

\begin{verbatim}
eulisp-handler:0:sockets!1>
\end{verbatim}

\noindent
signifies that the top-level handler is executing on thread {\tt 0},
the current module focus is {\tt sockets} and that the command history
index of this line is {\tt 1}.  The following operations are defined
in the {\tt root} module:

\keyword{reload-module}
\begin{arguments}
\item[symbol] name of the module to load.
\end{arguments}
\keyword{!>>}
\begin{arguments}
\item[symbol] name of the module to load.
\end{arguments}
\result the name of the module.

Reload the specified module.  This has the side-effect of resetting
the exported bindings of the module, such that any importing module
will reference the new values.  This operation may be abbreviated to
{\tt !>>} which will cause the specified module to be reloaded and
change the focus to that module.  Unlike {\tt reload-module}, {\tt
!>>} is recognized everywhere.

\standard{load-loudly}
\result A boolean.

Switch on verbosity of monitoring during module loading.

\standard{load-quietly}
\result A boolean.


Switch off verbosity of monitoring during module loading.

\standard{loaded-modules}
\result A list of the names of the currently loaded modules.

\keyword{(!>}
\begin{arguments}
  \item[module] Name of module to load.
\end{arguments}
\keyword{enter-module}
\begin{arguments}
  \item[module] Name of module to load.
\end{arguments}
\result If {\em module-name} names a module which has been loaded,
then the top-level is changed to be in that module.  If a module named
{\em module-name} is not currently loaded, then \feel\ tries to load
the module from a file called {\em module-name}{\tt.em}.  If loaded
succesfully, top-level is changed to be in that module.  This
operation may be abbreviated to {\tt !>}.  However, it is also
important to note that whilst {\tt enter-module} is only defined in
{\tt root}, {\tt !>} is recognized everywhere.

\keyword{start-module}
\begin{arguments}
  \item[module-name] Name of a module
  \item[function-name] Name of a function
  \item[arg] argument
\end{arguments}
\result 
Calls the function {\em function-name} in the module {\em module-name}
with the arguments {\em arg}\/$^*$.

\keyword{load-module}
\begin{arguments}
  \item[module-name] A symbol
\end{arguments}
Load the specified module.

\medskip
\accessor{load-path}
\updator{load-path}
\result
{\tt load-path} returns a list of strings which define the paths
currently searched when loading modules and accessing documentation.
The setter function permits this load path to be modified dynamically.
\\
In addition, the following features are provided for controlling the
focus of the top-level:

\keyword{\tt !root}

Changes top-level back to the {\tt root} module.

\keyword{\tt !exit}

Within a handler loop, returns to previous top-level.  At top-level,
\eulisp\ terminates.

\keyword{\tt !{\it n}}

Redo the input sequence number {\tt n}.

\keyword{\tt !backtrace}
\keyword{\tt !b}
\keyword{\tt !q}
Within the handler loop, prints out a backtrace of function calls and
their environments.  This may be abbreiviated to {\tt !b}.  A simpler
backtrace, only containing the function calls, can be printed out by
typing {\tt !q}. The {\tt eulisp0} module exports a function, {\tt !B}
(not a special form) which may do a better job in some circumstances,
but is more prone to infinite loops.

\section{Start-Up Configuration}
\feel's default starting behaviour may be modified in two ways \ldots

\begin{description}
\item[Command Line Arguments]
  The interpreter recognises a number of command line arguments which
  are basically -heap, -stack-space and -do but you didn't want to know that. Actually:

  \begin{description}
  \item[-heap $n$] The size of heap to use (in megabytes if $n<50$, else
    bytes). Feel needs at least a 1.5 meg heap.
  \item[-do $cmds$] A list of things to do on startup
  \item[-stack-space $n$] Amount of storage to allocate for stacks and
    static data. This defaults to 1, but should be more for programs
    that use threads.
  \item[-boot] Name of bytecode image file to load. See later
  \item[-map] Produce bytecode map. See later.
  \item[-procs $n$] Start up using n processors. Works in SystemV
    configuration only.
  \item[-stack-size] The size of the interpreter stack. Default 32,
    max is 64. it should note be necessary to change this unless your
    program stops with a stack-overflow message. Beware that an
    infinite non-tail recursion problem may also trigger this message.
  \end{description}

\item[A Configuration File]
  Having first processed its command line arguments, \feel\ then looks
  for a file called {\tt .feelrc} in the {\tt \$HOME} directory of the
  user\footnote{Likely to be elsewhere on non-UNIX systems}.  If found,
  the file is read and the expressions within executed as if entered at
  top level.

\end{description}

\section{Objects}
The \eulisp\ object system is called \telos.  Every data item in
\eulisp\ is part of the class hierarchy.  Simple classes can be
defined by {\tt defstruct}, more complex classes with {\tt defclass}.
There is no message send primitive in \eulisp, instead generic
functions are used.  \telos\ has been designed to offer
programmability, efficiency and flexibility and the next three
subsections attempt to illustrate the kinds of things you can do with
it by means of a few examples.

\subsection{Generic Functions}
You see, it's like this\dots\footnote{to quote Keith}

\subsubsection{Univariate polynomials over the integers}
We start with a polynomial structure: this is a single term, with a
reductum that is the rest of the polynomial. A reductum that is an
integer marks the end of the polynomial.  A term consists of the
leading degree and the leading coefficient.
\beginlisp
(defclass <polynomial> (<number>) 
  ((ldeg accessor ldeg initarg ldeg initform 1)
  (lc accessor lc initarg lc initform 1) 
  (red accessor red initarg red initform 0))
constructor make-polynomial)
\endlisp

We define a method on {\tt equal} so we can check if two polynomials
are the same. Notice we do not have to check for the bottoming-out of
the recursion on the reducta: the generic nature of {\tt equal}
ensures that when we get to the end of a polynomial (and we have an
integer as a reductum rather than a polynomial) a different method is
called.  This relies on the fact that equal-methods for (int, poly)
and (poly, int) do not exist: the generic function discriminator
chooses the nearest applicable method on {\tt equal}, which in this
case is ({\tt object}, {\tt object}). This method returns {\tt ()} (as
the args cannot be {\tt eq}), which is just what we want.

\begin{verbatim}
(defmethod equal ((p <polynomial>) (q <polynomial>)) 
  (and (equal (ldeg p) (ldeg q))
       (equal (lc p) (lc q)) (equal (red p) (red q))))
\end{verbatim}

We now need some operations on this new type. If we are trying to add
polynomials to integers, we would like some method for converting
between integers and polynomials. We  use the function {\tt
lift-numbers} to do this.
\beginlisp
  (defmethod lift-numbers ((i <integer>) (p <polynomial>))
    <polynomial>)

  (defmethod lift-numbers ((p <polynomial>) (i <integer>))
    <polynomial>)

  (defmethod (converter <polynomial>) ((x <integer>))
    (make-polynomial 'lc x 'ldeg 0))
\endlisp
Now if we call any operation with a polynomial and an integer, the
integer is lifted to class polynomial, and the operation proceeds as
normal. For two polynomials, the method is easy. A minor wrinkle is
when the leading terms cancel: we must take care not to have a leading
coefficient of 0.
\beginlisp
  (defmethod binary-plus ((p <polynomial>) (q <polynomial>)) 
  (cond ((= (ldeg p) (ldeg q))
    (let ((sum (binary-plus (lc p) (lc q))))
      (if (zerop sum) (binary-plus (red p) (red q))
        (make-polynomial 'ldeg (ldeg p) 'lc sum 'red 
        (binary-plus (red p) (red q)))))) 
   ((< (ldeg p) (ldeg q))
    (make-polynomial 'ldeg (ldeg q) 'lc (lc q) 
                     'red (binary-plus p (red q))))
   (t (make-polynomial 'ldeg (ldeg p) 'lc (lc p)
                       'red (binary-plus (red p) q)))))

  (defmethod binary-difference ...
\endlisp
and so on for the other arithmetic operations. Also we would put new
methods on {\tt generic-prin} and {\tt generic-write} to print out the
values of polynomials using a suitable syntax.

\subsection{Classes}
Classes in \eulisp\ are not static items: they can be defined and
created dynamically just as any other type in the system. The
following example demonstrates this by defining a class whose
instances are themselves classes, whose instances are modular numbers.
The intermediate classes are parameterised by an integer, which are
the bases for the modular rings.  This also illustrates the use of
metaclasses, which control the structure of classes.

We create a metaclass {\tt <zmodn>} which is the class of the classes
\classname{Zmod3}, \classname{Zmod5}, \classname{Zmod7}, etc.
\beginlisp
  (defclass <zmodn-class> (<class>)
    ((n initarg n reader zmodn-class-n))
    metaclass <class>)
\endlisp

This will be a direct subclass of {\tt class}, and so will inherit its
methods, in particular the ability to create subclasses which are
themselves classes.  The instances of this class will have a slot
named {\tt n}, which will be the modular base.

Now we define a superclass for all of its instances, to place them in
their own sub-hierarchy of the class graph.  This class has an
instance variable {\tt z}, since the instances of its subclasses are
the fully instantiated modular numbers.
\beginlisp
  (defclass <zmodn-object> (<number>)
    ((z accessor zmodn-z))
    metaclass <zmodn-class>)
\endlisp
The metaclass of the instances of {\tt zmodn-object} is defined to be
the class {\tt zmodn-class}. Thus the structure of the instances (the
classes {\tt Zmod5}, etc.) is determined by {\tt zmodn-class}.

The constructor for the instances of {\tt zmodn-class} (the metaclass)
could be the following:
\beginlisp
 (defun make-zmodn-class (n)
    (make <zmodn-class>
	  'direct-superclasses (list <zmodn-object>)
	  'name (make-symbol (format nil "<zmod-~a>" n))
	  'n n))
\endlisp
The {\tt make-instance} requires values for the slots in {\tt
zmodn-class}, which include {\tt n} (the slot we defined), and {\tt
direct-superclasses}, a slot inherited from {\tt class}.

If you want to avoid creating duplicate {\tt zmodn} classes with the
same N, try this definition instead:
\beginlisp

  (defconstant *zmodn-table*
     (make <table> 'comparator = 'hash-function generic-hash))

  (defun make-zmodn-class2 (n)
    (or (table-ref *zmodn-table* n)
	(let ((cl (make-zmodn-class n)))
	  ((setter table-ref) *zmodn-table* n cl)
	  cl)))
\endlisp

The function to create the modular objects themselves could be defined
as follows:
\beginlisp
  (defun make-modular-number (z n) 
     (make-instance (make-zmodn-class2 n) 'z z))
\endlisp
Note that this implemenatation guarentees that the number is of the
appropriate range:
\beginlisp
  (defmethod initialize ((proto <zmodn-object>) lst)
    (let ((i (call-next-method)))
      ((setter zmodn-z) i 
       (remainder (scan-args 'z lst required-argument) 
		  (zmodn-n i)))
      i))
\endlisp
  
Getting {\tt z} from one of these instances is already defined by the
reader on {\tt zmodn-object}.  Getting {\tt n} involves going to the
class.  Making this available from instances means defining the
following function:
\beginlisp
  (defgeneric zmodn-n (obj))

   (defmethod zmodn-n ((z <zmodn-object>))
     (zmodn-class-n (class-of z)))
\endlisp

Next, we want to define some simple arithmetic on modular numbers, for
example, addition. However, this only makes sense if we have the same
modulus in both of the summands.
\beginlisp
  (defun compatible-moduli (n m) (if (= (zmodn-n n) (zmodn-n m)) t
    (error "incompatible moduli" Internal-Error)))
\endlisp

We define a method for addition on {\tt <zmodn-object>}: this will then
be inherited by each instance, viz., the actual rings {\tt <zmod3>},
{\tt <zmod5>}, and so on.
\beginlisp
  (defmethod binary-plus ((n1 <zmodn-object>) (n2 <zmodn-object>)) 
    (when (compatible-moduli n1 n2) 
      (make-modular-number (+ (zmodn-z i) (zmodn-z j)) 
			   (zmodn-n i))))
\endlisp

We can add a method to the print function to view numbers prettily
\beginlisp
  (defmethod generic-prin ((n <zmodn-object>) s) 
    (format s "~a<mod ~a>" (zmodn-z n) (zmodn-n n)))
\endlisp

Finally, some examples of numbers
\beginlisp
  (deflocal zero5 (make-modular-number 0 5)) 
  (deflocal one5 (make-modular-number 1 5))
  (deflocal two5 (make-modular-number 2 5))
  (deflocal three5 (make-modular-number 3 5))
  (deflocal four5 (make-modular-number 4 5))
  (deflocal zero3 (make-modular-number 0 3)) 
  (deflocal one3 (make-modular-number 1 3))
  (deflocal two3 (make-modular-number 2 3))
\endlisp

Now if we try an addition:
\begin{verbatim}
> (+ two5 four5)
< 1<mod 5>
\end{verbatim}
We didn't have to specify a plus method for each modular ring
individually: the single definition on the superclass suffices.

Thanks to Harley Davis for help on this section.

\subsection{Slot Descriptions}
Another aspect of the programmability of \telos\ is slot-descriptions.
This allows the user to control how the slots of a class are accessed.
Here we present an example of the use of slot-descriptions to provide
a classed (typed) slot facility.  The aim is to be able to define a
class and, at the same time, the class of the values to be associated
with a given slot.  The solution is to define a new kind of
slot-description to verify that only values of the correct class are
stored in the slot.  We start by defining a new kind of
slot-description {\tt <classed\--local\--slot-description>}.

\beginlisp
 (defclass <classed-local-slot-description> (<local-slot-description>)
    ((contents-class initform <object> initarg contents-class
		     reader classed-local-slot-description-contents-class))
    metaclass <slot-description-class>)
\endlisp

The classed-local-slot-description class inherits the normal slots
from \classname{local\--slot\--description} and adds somewhere to keep
track of the allowed class of its contents.

To police the class (type) constraint, we must check that whenever a
value is written to a slot with this class---that the value is of the
specified kind. we therefore want a new method on {\tt
compute\--primitive\--writer\--using-slot\--description}. 
\beginlisp
  (defmethod compute-primitive-writer-using-slot-description 
    ((csd <classed-local-slot-description>) cl lst)
    (let ((std-writer (call-next-method))
      (contents-cl (classed-local-slot-description-contents-class csd)))
      (lambda (obj val)
        (if (subclassp (class-of val) contents-cl)
            (std-writer obj val)
          (error "invalid class of value for slot"
                 some-error 'object obj 'sd csd 'val val)))))
\endlisp

The call to the standard writer is reached only if the value satisfies the
class constraint. It just means the value is acceptable---go ahead and
do whatever you normally do to put the slot value inside.

All that remains is how to use one of these slots in a class. The
example you give can be done as follows---but remember that {\tt
defclass} must be used instead of {\tt defstruct} because the latter
does not support user-defined slot classes.

\begin{verbatim}
  (defclass <person> ()
    ((age slot-class <classed-local-slot-description>
          initarg age
          slot-initargs ('contents-class <integer>) accessor age)
     (name slot-class <classed-local-slot-description>
           slot-initargs ('contents-class <string>)
           accessor name) 
     (ordinary-slot initform 'bleagh))
    )
\end{verbatim}

The slots {\tt age} and {\tt name} are of the new class of slot with
their contents class set to {\tt integer} and {\tt string}
respectively.  Of course, other slots with different classes of slot
description may also be defined.

Now, we may type the following:

\begin{verbatim}
  (setq i (make <person>)) ((setter age) i 27)
\end{verbatim}

\noindent
which is fine and {\tt (age i)} will return {\tt 27}.

\begin{verbatim}
  ((setter age) i 'not-a-number)
\end{verbatim}

\noindent
but this signals an error.  Thanks to Luis Mandel for prompting this
example.

\subsection{Mixins}

\feel\ supplies a mixin module\footnote{called \filename{mixins}} to
allow the use mixin classes \`a la flavors\comment{right?}. A mixin
class is a class that can be used in a multiple inheritance network,
but has certain restrictions to enable the creation of more efficient
accessors---multiple inheritance is restricted to non-instantiable
classes and these classes, {\em mixins}\ are then used for
specialisation of instantiable objects, {\em base-objects}. Mixins
tend to be used to describe attributes of objects, and then these are
``mixed in'' with base classes to create specialized classes. The
mixin implementation has two metaclasses
\begin{itemize}
\item \classname{mixin-class} The class of a mixin class
\item \classname{mixin-base-class} The class of a base-object class 
\end{itemize}

Instances of \classname{mixin-class} are not instantiable, but allow full MI.
Only instances of \classname{mixin-base-class} may inherit from
mixin-classes, and the list of direct superclasses of a
\classname{mixin-base-class} must have all mixin-classes before a
single non-mixin class (In \feel, it may inherit from any other class in
the system, including \classname{class}).

\begin{figure}
\beginlisp
(defclass <point> ()
  ((x initform 0 accessor point-x initarg x)
   (y initform 0 accessor point-y initarg y))
  )

(defclass <colored> ()
  ((color initform 'black initarg color 
	  reader color))
  metaclass <mixin-class>)

(defgeneric color-of (obj)
  method (((obj <object>)) 'gray)
  method (((obj <colored>))
	  (color obj)))

(defclass <colored-point> (<colored> <point>) 
  ()
  metaclass <mixin-base-class>)

(setq p1 (make <point>))
(color-of p1)

(setq p2 (make <colored-point> 'x 1 'y 1 'color 'red))
(color-of p2)
\endlisp
\caption{Usage of mixin inhertance}
\end{figure}
Note on the implementation: \classname{mixin-class} has a different
default slot type, \classname{mixin-slot-description}. When this slot
is inherited {\em directly} by a \classname{mi\-xin-base-cl\-ass} its
the accessor is computed. If the slot is not newly created, however,
no new access method is computed, therefore reducing the number of
such methods for a given accessor. 

\section{eql methods}

These are supplied bye the eql module. Effectively it defines new
generic function and method classes, and allows eql methods to be
defined. See \filename{eql.em} for full details.

\section{Differences between FEEL and EuLisp}

Inevitably there are a number of minor ways in which \feel is not an
accurate implementation of \eulisp.  This section outlines these
differences.  The 0.98 version is taken as the main version.

The whole of Level 0 is implemented.  Much of Level 1 is also running.
The library modules (section 5 of \eulisp 0.69) are much more patchy.

A major area of incompatability is in the conditions, some of which
are not used when the document says they should.  This is being
improved daily\footnote{at least that is the intention!}

\subsection{Input and Output}

The \eulisp definition does not yet have a powerful input/output
mechanism. The one in \feel is intended to be a starting point, and no
more. It provides input and output primitives, plus scan and format.

\subsection{Elementary Functions Module}

None of the elementary functions are implemented on integers. 
\subsection{Formatted-IO Module}

The function {\tt format} is defined, and understands the esacapes
{\tt \~{ }a}, {\tt \~{ }s}, {\tt \~{ }t}, {\tt \~{ }\%} and {\tt \~{
}\~{ } } only.  It also implements the additional escape {\tt
\~{ }u} for printing lists with hexadecimal values for system debugging.
The numerical formats for binary, octal decimal and hexadecimal are
only implemented for fixed integers.  The treatment of the field sizes
in g, e and f formats are very inconsistent.

\section{Pretty printing}
There is an elementary prettyprinter in the module {\tt pretty}.  It
exports the following three functions.

\standard{prettyprint}
\begin{arguments}
\item[object] Object to print
\end{arguments}
\result
The answer is the same as the argument, but as a sideffect a
pretty-printed form of the object is printed.  The layout is
controlled by a table which can be modified.  In theory (but not yet
in practice) setting the variable {\tt *symmetric*} controls whether
the printed form is capable of re-entry. The code also shows how one
adds new stream-type objects to the system.

\section{AVL tree Module}

{\em To be written}
The source code is a reasonable description

\section{OPS5 Module}

{\em To be written}

\comment{
\section{Graphics}
\def\level{YY}
To minimise our implementation effort and to maximise portability and
familiarity, \feel\ is interfaced to the X-Windows system.  However,
we decided that a direct interface to the X server such as provided by
CLX in Common was too low-level for the majority of the operations we
wanted (clearly this is a personal viewpoint) and so we use the YY
server developed by Masayuki Ida and his resarch team at Aoyama Gakuin
University.  The YY server provides a higher level of abstraction than
the X server at the cost of more communication and another heavyweight
process.  Thus, \feel\ sockets to YY and YY sockets to X.
Documentation for the YY system itself is provided separately.  This
section contains details of the Eulisp to YY interface package.  The
package comes in 3 parts: a server, a low level interface and an API.
It is available by anonymous ftp from {\tt ftp.csrl.aoyama.ac.jp}. For
further information contact the YYonX mailing list---{\tt
yyonx@csrl.aoyama.jp}. The program as delivered, comprises a client
and a server. The client is an Applications Program Interface (API)
written in \cl\ and \clos\ and is not used by the \feel\ system.

%% pab --- (changed server to client :-)
\subsection{The YY server}
The YY server is the program which connects to an X display from an
application program (the client). It acts on the commands of the
client, and conveys input to the display back to the client, after a
filtering stage.  Because it works over internet sockets, it can run
on any machine on the local net, and so need not compete for CPU
cycles with \feel.  \feel\ can use any X windows display for its
output as long as the machine running the server has permision to use
that display. Thus up to three machines can be involved in the process
of producing a picture. The server currently runs on sun-3 and sun-4
machines, and may have difficulty communicating with machines which
use a different byte order.

\subsubsection{Starting the YY Server}
The server is started from the YY-server directory with the command
{\tt serv}. There is a {\tt -p} {\em $<$arg$>$} option which selects
the port number. The argument should be a non-negative even number.
The port number defaults to 0.

\subsection{The Eulisp YY module}
The YY interface requires a number of extra C level functions, which
are compiled and linked to make a distinct executable called 'look' or
similar in the distribution.

These C functions can be accessed via the {\em YY} module, together
with some functions to make them simpler to use.  This module should
contain all the necessary functions to connect and run a YY session.
Any function that is not included in the module but defined within the
YY protocol specification should be in the module, although several
have not yet been implemented in the server and therefore cannot be
used by the module. The details of the connection to the server,
including a description of the low level interface are described in a
later section.

\subsubsection{Connecting to the YY-Server}
Before connecting to the server, the program must ensure that the
server is running and able to connect (or not be over-worried about
breaking at this point).  The normal way is one of:
\begin{itemize}
\item
ask the user to type {\tt serv} on an appropriate machine
\item
run a remote-shell command, for instance:
\begin{center}
{\tt (system  "rsh $<$server-host$>$ serv")} 
\end{center}
\item
hope that the server is running.
\end{itemize}
\noindent
The third is the usual option, and can easily be achieved by invoking
\eulisp\  from a shell script, which also starts the server program.

\standard{YY-connect}{server port}{boolean}
This function that makes the connection from \eulisp\ to the YY
server.  {\em server} is the name of the machine running the server,
and {\em port} argument should be equal to the {\tt -p} option given to the
{\tt serv} command, or {\tt 0} if the {\tt -p} option was not given.

\standard{initialise-server}{X-display Window-name Icon-name}{structure(Info)}
After connecting, the server must initialise the YY server with the
name of the X11 display to use. This is relative to the server, so
specifying ``unix:0.0'' means the console display of the machine
running the server. The name of the window, in its normal and
iconified form should also be specified. An object of type {\em Info},
which  can be used to query various constants about the display (eg.
display resoloution, etc) is returned.

\standard{YY-initialised-p}{}{bool}
Returns true if initialise-server has been called.

\subsection{Territories}
The central class of object for manipulating graphics is the
{\em Territory}. A territory has the ability to display data, be moved
and raised or lowered relative to other territories. The concept is
very similar to that of windows in the X11 world, except that the
programmer has more control over their movement. They provide the
means by which functions reference the display, and allow input from
the user. The coordinate frame used by territories is that of
X-windows: X ordinates increasing left to right and Y ordinates
increasing from top to bottom, both relative to the top left corner of
the territory. There is no facility to rescale these at the server
layer. 

\subsection{Input-Territories}
Not yet available

%% This section will be written the interface (Ho Hum)

\subsection{Classes}
In this section the function interface to the classes is decribed. The
interface is not yet complete, so a selection of the functions
available is given.

\subsubsection{Territory}

\standard{make-Territory}{initlist}{Territory}
A new territory is created by {\tt make-Territory} (via
{\tt make-instance}). This also informs the server of the territory's
existence. The following initargs are used:
\begin{description}
\item [parent] this argument is an object of class {\tt Territory}, or
  {\tt nil}. {\tt nil} specifies that the object is a root territory,
  and therefore has no parent. It is not an error to have more than one
  root territory
\item [area] this must be an object of class {\tt Area}, and specifies
  the size and position (relative to the parent) of the territory
\item[top left bottom right] Specify the area as above. If the {\tt
  area} initarg is given, then it takes precedence
\item [visible] specifies whether the window can be displayed by the
  X-server. If this is {\tt nil}, then the territory is can only be used
  as a temporary store for pixel data.
\item[drawable] some territories can be used for reading input
  information holding only, or as a place holder in the tree of
  territories. The root territory should not be specified as drawable
  and therefore cannot be used for drawing.
\end{description}

\standard{clear-territory}{colour}{null}
Clears the territory to the specified colour.

\standard{move-territory}{territory point}{null}
Moves the territory to the specified point

\standard{destroy-territory}{territory}{null}
Kills the specified territory.

\standard{display-territory}{territory}{null}
If flag is true then map the territory, if nil, hide it.

\standard{Territory-width}{territory}{number}
\standard{Territory-height}{territory}{number}
\standard{Territory-top}{territory}{number}
\standard{Territory-left}{territory}{number}
Give the approporiate dimension of the territory.

\subsubsection{Colours}

\standard{make-Colour}{arg-list}{Colour}
makes an instance of class {\tt Colour}. It takes the following
initargs:
\begin{description}
\item [red] an integer in the range [0,66535]
\item [green] an integer in the range [0,66535]
\item [blue] an integer in the range [0,66535]
\end{description}

These specify the amount of red, green and blue in the colour. The
actual colour displayed on screen is defined by the X display that the
server is connected to. The initargs may be abbreviated to {\bf r},
{\bf g}, and {\bf b} respectively.

\standard{Black-Colour}{}{Colour}
\standard{White-Colour}{}{Colour}
Returns the appropriate colour, or nil if the YY server is not yet
connected.

\subsubsection{Fonts}

\standard{load-font}{fontname}{Font}
This function loads a font into the server. The font must be specified
in the {\tt yyfontinfo} file in the YY-server directory.

\standard{Std-Font}{}{Font}
Returns the standard font (called ``fixed'' in this implementation),
defined by the constant *Std-Font* in the YY module.

\subsection{Drawing functions}
The drawing functions are direct calls on the YY server, and, in
consequence, take a large number of arguments, most of which are not
used.  For an example of a higher level interface see the {\tt
turtle}\ module described later in this document.

The {\tt op} parameter is a flag describing the bitblt operation
needed to render the object on the screen. It may take the following
values:  {\tt GCLEAR, GAND, GANDREVERSE, GCOPY, GANDINTEVERTED, GNOOP,
GXOR, GOR, GNOR, GEQIV, GINVERT, GORREVERSE, GCOPYINVERTED,
GORINVERTED, GNAND or GSET}. What these operations achieve is
specified in the Xlib manuals.
The {\tt edge} parameter may take the following values: {\tt
SQUARE-LINE-EDGE, SQUARE-LINE-EDGE-WITHOUT-END, or ROUND-LINE-EDGE},
again specified in the X-manuals.

\standard{draw-point-xy}{territory x y op colour}{null}
Draws a point at the specified $(x,y)$ point using the specified
operation and colour. 

\standard{draw-line-xy}{territory x1 y1 x2 y2 width op edge colour dash}{null}
Draws a line form $(x1,y1)$ to $(x2,y2)$ using the specified width,
operation, edge type and colour. The dash parameter is currently
ignored.

\standard{draw-string-xy}{territory x y op colour font string}{null}
Writes the string onto the territory at $(x,y)$ using the specified
operation and colour.  The $y$ coordinate is the baseline of the text.

\standard{draw-string-centred}{territory x y op colour font string}{null}
Draws the string with its centre at $(x,y)$.

\standard{draw-filled-rectangle-xy}{territory x y w h op colour
source-territory}{null}

Draws the specified rectangle filled using the colour, and using the
source territory as a mask. If this is null, then the territory is
simply filled according to the given operation.

\standard{draw-circle-xy}{territory x y r width op colour dash}{null}
Draws a circle of radius $r$ centred at $(x,y)$. The other arguments
are as {\tt draw-rectangle-xy}.

\standard{draw-filled-circle-xy}{territory x r y op colour source-territory}{null}
Similar to draw-filled-rectangle-xy.

\standard{bitblt-xy}{src-territory s-left s-top dest-territory
dest-left dest-top width height op}{null}
General-purpose block copier. Copies bits from the source location to
the destination an area of the specified width and height. NB: This
function is at present unimplemented.

\subsection{Input Functions}
Listed here are the low level functions for getting events from the
server. A higher level, widget based module is contained in the
modules {\tt dispatcher},{\tt widgets} and {button}. This is currently
under development, so the exact interface is not described here.

\standard{combine-input-mask}{event-type-1 . events}{event-mask}
Returns an event mask suitable for use by {\tt set-event-mask}. The
event-type can be any of: {\tt BUTTON-1-DOWN, BUTTON-2-DOWN,
BUTTON-3-DOWN, BUTTON-1-RELEASE, BUTTON-2-RELEASE, BUTTON-3-RELEASE,
MOVE-BUTTON, ENTER-TERRITORY, EXIT-TERRITORY, STAY-TERRITORY,
BUTTON-1-DOUBLE-CLICK, BUTTON-2-DOUBLE-CLICK, BUTTON-3-DOUBLE-CLICK,
INTERRUPT-KEY-DOWN, META-KEY-DOWN, CONTROL-KEY-DOWN, SHIFT-KEY-DOWN}.

\standard{set-event-mask}{territory event-mask}{event-mask}
Sets the event mask on the specified territory. Events that occur in
the specified territory which are included in the event-mask will then
be placed on the input queue.

\standard{read-next-event}{}{event-list}
Waits (blocks if \feel\ is single-threaded) for an event on the input
queue. The retuned value is a vector consisting of the territory that
received the event, a bit-vector representing the event and the
location of the cursor when the event occured. If an event occured,
\begin{center}
 {\tt (bit-vector-ref $vect$ $event$)}
\end{center}
returns 1, otherwise it returns 0.

\standard{sample-next-event}{}{event-list / null}
If an event is on the input queue, return it as above, otherwise,
return {\tt nil}.

\subsection{Input Classes}
Will be coverered later.
%% Not yet implemented

\subsection{Utility Classes}

\subsubsection{Area}

\standard{make-Area}{initargs}{Area}
\standard{Area-top}{Area}{number}
\standard{Area-left}{Area}{number}
\standard{Area-bottom}{Area}{number}
\standard{Area-right}{Area}{number}
\standard{Area-width}{Area}{number}
\standard{Area-height}{Area}{number}

An area is specified by its top left coordinate and its bottom right
coordinate. 

\subsection{Any Other Business}
An example of a YY application is given in the appendix.
}
\section{Thread Abstractions}
\eulisp\ provides a set of primitive operations for thread creation
and manipulation, but for most work these are too low-level and
require the user to be overly concerned with their management.  It is
also true that one of the design goals of \eulisp\ was to provide an
experimentation environment for parallel processing, so it should not
be surprising that several thread abstractions have been built on the
\eulisp\ thread primitives.  So far these abstractions comprise: {\em
futures}, {\em linda} and {\em timewarp}.  The next three subsections
describe them in detail.

\subsection{Futures}
% Note that some of these have changed. look in futures.em for the
% details 

\def\level{Future}
The nature of the \eulisp\ thread mechanism means that it lends itself
quite naturally to providing a base for the implementation of a simple
future abstraction. The acts of creating futures and of eventually
interrogating them for their values map almost directly onto starting
threads and accessing thread results.

The code for basic future manipulation is given below. A couple
of examples of replacements for ``strict'' functions that allow for
future objects are shown. The extensibility of generic functions and
module renaming can be used to make these necessary changes
transparent for users.

\macro{future}

\syntax
\noindent
{\em \group{{\tt future} {\group{expression$^*$}}}}

\remarks
Constructs a future object and spawns a thread to calculate the value
of {\em expression}.  An object of class {\em future} is returned by
the expression resulting from the macro expansion.  The implementation
of {\tt future} in \feel\ is:

\begin{verbatim}
  (defmacro future exp
    `(let 
       ((future (make-future-object))
        (task (make-thread 
                (lambda (future fun)
                  ((setter future-object-value) future (fun))
                  ((setter future-object-done) future t)
                  t))))
         ((setter future-object-thread) future task)
         ((setter future-object-function) future (lambda () ,@exp))
	 (thread-start task future (lambda () ,@exp)) 
	 future))
\end{verbatim}

\medskip
\gen{futurep}
\begin{arguments}
\item[obj] The object to be tested
\end{arguments}
\result nil if obj is not a future, otherwise, non-nil.

\medskip

\standard{future-value}
\begin{arguments}
\item[future] The value to be evaluated
\end{arguments}
\result
Forces the evaluation of a {\em future} and if the result of the
evaluation is also a {\em future} that too is forced until the result
is not a {\em future}.

\standard{future-select}\begin{arguments}
\item[list] a list of futures
\end{arguments}
\result 
Return the first of future-list to complete 

\subsection{Linda}
{\em To be written}. See \filename{eulinda.em}

\subsection{Communicating Sequential Processes}
\def\level{CSP}
The CSP module provides a new class of thread, called a {\tt
CSP-thread}, the channel class and several syntactic extensions.
These extension are detailed below.


\subsubsection{Channels}
	
Channels are the basic form of interprocess communication in CSP. They
provide a means for 2 processes to communicate via a synchronous link.
In this version of CSP there area two types of channel: the simple
channel and the channel pair. A simple channel is specified at
dynamically by the functions {\tt connect-channel-input} and {\tt
connect-channel-output}. Only {\tt IN} operations are permitted on the
channel returned by the former, and only {\em OUT} operations on the
latter. These operations are only alowed on the thread that connected
the channel or one that it created. A channel pair is made up of two
channels and is connected to a thead by {\em connect-chan-pair}

\subsubsection{Bindings}


%% Design Note:
%% Some of the constructs return values, while in a strict version of CSP
%% this form of communication is disallowed. However, the function
%% invocation, value passing and returning reults could be viewed as
%% setting up channels, sending data down them and reading the return
%% values back from the channels. 
%%

\standard{make-Channel}
\result
Returns an unconnected simple channel

\standard{make-Chan-Pair}
\result
Returns an unconnected channel pair

\standard{connect-channel-input}
\begin{arguments}
\item[channel] a channel
\end{arguments}
\result 
A channel. Connects the thread executing the statement to the
input end of the channel.

\standard{connect-channel-output}
\begin{arguments}
  \item[channel] A channel
\end{arguments}
\result A channel. Connects the thread executng the statement to the
output end of the channel.

\standard{connect-chan-pair}
\begin{arguments}
\item[channel-pair] A channel pair
\end{arguments}
\result
Returns one end of the specified channel as a connected channel. 

\macro{IN}

\syntax
\noindent{\em\group{{\tt IN} channel \optional{variable}}}

\remarks
Waits until transmitter (process on the other end of {\em channel}) is
ready to send data (signaled by doing {\tt OUT} on {\em channel}) and
then reads the object from {\em channel} assigning it to {\em
variable}. If the {\em variable} is ommited, IN simply returns the
value on the channel.

\macro{OUT}

\syntax
\noindent{\em\group{{\tt OUT} channel obj}}
\remarks
Waits until reciever (process on the other end of channel) is ready to
receive data (by doing {\tt IN}) and then outputs {\em obj} to the
channel {\em channel}.

\macro{PAR}

\syntax
\noindent{\em\group{{\tt PAR} expression$^*$\/}}
\remarks
The expression can be any lisp expression. Execute each {\em
expression} as a seperate thread. The construct waits until all its
subexpressions have completed, and returns a list of values returned
by the expressions. 

\macro{MAPPAR}

\syntax
\noindent
{\em\group{{\tt MAPPAR} function list}}
\remarks
Apply {\em function}, which should take one argument to each element of the
list, as a parallel operation. 

\macro{FOR}
\remarks
PAR as iteration over a sequence of values.

\macro{ALT}
\syntax
\noindent
{\em\group{{\tt ALT} alternative$^*$}}
\remarks
Each alternative has the following form:
\begin{center}
((IN {\em channel} {\em variable})  expression$^*$)
\end{center}
When one one the listed channels is known to be ready, this executes
the code associated with the IN statement with the specified variable
bound to the next value on the channel. This construct should be 
viewed as non-deterministic -- ie. it does not necessarily return the
first ready channel.

%% I need a better name for this...
%%
\macro{IN-FROM}{ (channel-var value-var) channels . expressions}

\syntax
\noindent
{\em\group{{\tt IN-FROM} {\tt (} channel-var value-var {\tt)} channels \group{expressions}$^*$}}
\remarks
When one of the channels is known to be ready, the expressions are
evaluated with {\em channel-var} bound to the channel, and {\em
value-var} to the value on that channel.

\macro{SEQ}

\syntax
\noindent
{\em {\tt SEQ} {expression$^*$}}
The same as progn, ie execute the following expressions in the order given.
\subsection{Time Warp}
{\em To be written}

\section{Distributed Processing}
\def\level{\feel}
The basis for distributed processing in \feel\ under Unix is supplied
by the {\tt sockets} module, which exports the functions defined
below.

\standard{socketp}
\begin{arguments}
  \item[obj] An object
\end{arguments}
\result
If {\em obj} is a {\tt socket} returns {\tt t}, otherwise {\tt ()}.

\standard{make-listener}
\result
Allocates a fresh {\tt listener} object.

\standard{make-socket}
\result
Allocates a fresh {\tt socket} object. Note that this function is
almost never called.

\standard{listener-id}
\begin{arguments}
  \item[Listener] a listener
\end{arguments}
\result
Returns a pair, whose car field contains a symbol naming the local
host and whose cdr field is a port number on that host identified with
the listener.

\standard{listen}
\begin{arguments}
  \item[listener] a listener
\end{arguments}
\result
Listens on the port number returned by {\tt listener-id} applied to
{\em listener} and returns {\tt socket} when a connection is
established.

\standard{connect}
\begin{arguments}
  \item[pair] A pair identifying a listening port on a remote machine
\end{arguments}
\result
The pair contains the information returned by {\tt listener-id} and
makes a connection to the named machine on the specified port,
returning {\em socket} which is the handle on the established
connection bewteen the two processes.

\standard{close-listener}
\begin{arguments}
  \item[listener] a listener
\end{arguments}
\result
Changes internal state of {\em listener} so that it can no longer be
used for listening.

\standard{close-socket}
\begin{arguments}
  \item[socket] a socket
\end{arguments}
Flushes all pending data related to {\em socket} and changes the
internal state of {\em socket} so that it is no longer readable or
writable.

\standard{socket-readable-p}
\begin{arguments}
  \item[socket] a socket.
\end{arguments}
\result
If there is data available for reading from {\em socket}, returns {\tt
t}, otherwise {\tt ()}.

\standard{socket-writable-p}
\begin{arguments}
  \item[socket] A socket.
\end{arguments}
\result
If data can be written to {\em socket}, returns {\tt t}, otherwise
{\tt ()}.

Figure~\ref{sockets} is two scripts of a simple example of
establishing a socket connection and a dialogue across the connection

Currently {\tt socket-read} and {\tt socket-write} are used for input
and output. If you are comminicating with non-\eulisp processes then
you should use format/print and scan/input. {\tt Read}, for various
reasons cannot be used.

\begin{figure}[htbp]
  \begin{tabular}{|c|c|}\hline
    machine-1 & machine-2 \\\hline\hline
    \begin{minipage}[t]{7.5cm}
\begin{verbatim}
eulisp:0:root!0> (!> standard)
Loading module 'standard'
Loading module 'extras'
Loaded 'extras'
Loaded 'standard'
eulisp:0:standard!0< standard

eulisp:0:standard!1> (import sockets)
eulisp:0:standard!1< ()

eulisp:0:standard!2> (setq s
   (connect '(machine-2 . 1236)))

eulisp:0:standard!2< #socket(3,3)

eulisp:0:standard!3> (socket-read s)
eulisp:0:standard!3< 1

eulisp:0:standard!4> (socket-write s 2)
eulisp:0:standard!4< 2
\end{verbatim}
\end{minipage}
&
\begin{minipage}[t]{7.5cm}
\begin{verbatim}
eulisp:0:root!0> (!> standard)
Loading module 'standard'
Loading module 'extras'
Loaded 'extras'
Loaded 'standard'
eulisp:0:standard!0< standard

eulisp:0:standard!1> (import sockets)
eulisp:0:standard!1< ()

eulisp:0:standard!2> (setq l
   (make-listener))

eulisp:0:standard!2< #listener(3,1)

eulisp:0:standard!3> (listener-id l)
eulisp:0:standard!3< (machine-2 . 1236)

eulisp:0:standard!4> (setq s (listen l))
eulisp:0:standard!4< #socket(4,3)

eulisp:0:standard!5> (socket-write s 1)
eulisp:0:standard!5< 1

eulisp:0:standard!6> (socket-read s )
eulisp:0:standard!6< 2
\end{verbatim}
\end{minipage}
\\\hline
\end{tabular}
\caption{Example socket based communication}
\label{sockets}
\end{figure}

\subsection{Linda}
{\em To be written}
\subsection{Time Warp}
{\em To be written}

%% Documentation for PVM
\subsection{The PVM module}
\def\level{PVM}

The pvm module provides an interface to the pvm library. This section
assumes that the reader has read at least some of the pvm
documentation.

The module differs from the pvm library in the following ways:
\begin{itemize}
\item Arbitrary lisp expressions (including circular structures) may
  be sent from machine to machine
\item The format in which objects are sent is not the XDR
  format used by pvm, but an internal format. It is hopefully machine
  (and byte order) independent. See the section on the reader module
  for more details.
\item Several reads may occur simultaneously on separate threads
  \footnote{note that pvm is not yet interfaced to the System V
  version.}. In other words, it is possible to call thread-suspend
  during a read.
\end{itemize}

The module exports the following functions:

\standard{make-pvm-id}
\begin{arguments}
\item[string] A string
\item [id] An identifier
\end{arguments} 
\result
creates a pvm-id which can be used
to broadcast to a group of remote processes. Note that this is
simply a cons cell.

\standard{pvm-status}
\begin{arguments}
  \item[id] Identifier of a pvm-process
\end{arguments}
\result Query the status of the process with
id {\em id}.

\standard{pvm-send}
\begin{arguments}
  \item[dest] A pvm process identifier
  \item[type] The numeric type of the message
  \item[msg] The message (can be anything)
  \item[{\optional{reader}}] A reader which is used to write the message.
\end{arguments}
\result 
Send a message of type {\em type} to the process specified by
the id {\em dest} containing the value {\em msg}. If a reader is
specified it is used to handle any complex lisp types inside the
message.

\standard{pvm-recv}
\begin{arguments}
  \item[type] The type of message to be recieved
  \item[info?] Is Information on message wanted
  \item[{\optional{reader}}] A reader which is used to read the
    message.
\end{arguments}
\result
Block until a message of type {\em type} is recieved. If {\em info?}
is nil, then the message is returned. If {\em info?} is non-nil, a
list is returned in the following format: {\tt ({\em msg type from})}
where msg is the message, type is the type and from is the process-id
of the sending processes.

\standard{pvm-recv-multi}
\begin{arguments}
  \item[type-list] A list of possible message types
  \item[info?] Information on message wanted flag
  \item[{\optional{reader}}] A reader which is used to read the
    message.
\end{arguments}
\result
As pvm-recv, but blocks until a message which has a type in the
type-list.

\standard{pvm-initiate-by-type}
\begin{arguments}
  \item[type] Type of machine (string)
  \item[name] Name of the new process (string)
\end{arguments}
\result
Start a process on a host of the specified type with the name {\em
name}. It returns the pvm identifier of the process.

\standard{pvm-initiate-by-hostname}
\begin{arguments}
  \item[hostname] Hostname in which to start process
  \item[name] Name of the new process
\end{arguments}
\result
Start a process on the host with name {\em hostname} with the name
{\em name}

\standard{pvm-enroll}
\begin{arguments}
  \item[name] A string
\end{arguments}
\result
Enroll into pvm under the given name.  Must be called before any other
pvm function.

\standard{pvm-leave} 
\result
Exit from pvm-control. After this is called, all pvm functions return
an error message (except pvm-enroll).

\standard{pvm-probe}
\begin{arguments}
  \item[type] A message type
\end{arguments}
\result 
Test for messages of a given type.  Returns the type, or nil if no
message of that type is in the input queue.

\standard{pvm-probe-multi}
\result
Test for messages from a list of types. Not yet implemented (as of PVM
2.4). Can be simulated via probe.

\standard{pvm-whoami}
\result
Return the pvm-id (the value returned by enroll) of the process.


\standard{pvm-make-id-from-pair}
\begin{arguments}
  \item[Pair] A pair
\end{arguments}
\result 
Construct a pvm-identifier from a cons cell. Mostly used when passing
addresses around --- when a pvm-id is sent, it is read as a cons-cell.
This operation is now a null operation.

The other functions provided are
\begin{itemize}
\item pvm-barrier
\item pvm-ready
\item pvm-waituntil
\item pvm-terminate
\end{itemize}

The Feel versions are untested, but ought to work. See the PVM
documentation for details about their functionality.

\section{The Reader Module}
\def\level{Reader}
The reader module provides functions to read and write lisp forms as
bytevectors. It is intended to be reasonably machine independent,
although at the current time it falls a little short. The module
currently deals with reading and writing lisp forms for the pvm,
socket and dbm modules. 

The module exports the following interface
(for use in user modules):

%
% This file was automatically produced at Sun Mar 15 17:13:09 1992 by
% c2latex obread.h
%
\expandafter\ifx\csname indentation\endcsname\relax
\newlength{\indentation}\fi
\setlength{\indentation}{0.5em}
\begin{flushleft}
{$/\ast$\it{}\mbox{}\\
\hspace*{2\indentation}$\ast$ obread.h\mbox{}\\
\hspace*{2\indentation}$\ast$ interface for obread\mbox{}\\
\hspace*{2\indentation}$\ast/$}\mbox{}\\
\mbox{}\\
{$/\ast$\it{} class of the reader $\ast/$}\mbox{}\\
\mbox{}\\
{\bf extern} LispObject object\_reader;\mbox{}\\
\mbox{}\\
{$/\ast$\it{} functions $\ast/$}\mbox{}\\
\mbox{}\\
{\bf extern} {\bf void} write\_obj(LispObject $\ast$,LispObject, {\bf
unsigned}
{\bf char} $\ast$$\ast$,\mbox{}\\
\hspace*{22\indentation}LispObject);\mbox{}\\
{\bf extern} LispObject read\_obj(LispObject $\ast$,{\bf unsigned}
{\bf char} $\
ast$$\ast$, LispObject);\mbox{}\\
\mbox{}\\
{\tt \#define} EUBUG(x) \mbox{}\\
\end{flushleft}


The reader in its default form can read any 'simple' lisp expression
that is: integers, floats, strings, symbols\footnote{Support for
symbols may be removed in future versions because they may require
some caching, which will be provided by a lisp level}, lists and
vectors. The extensibility is provided via an extra argument which may
be supplied to control the reader's behaviour on complex lisp types. A
type here means a group of classes which can be read in the same way.
The type of an object is given by the integer identifier passed to
{\tt add-writer} and {\tt add-reader}.

\standard{make-obj-reader}
\result
Makes a new reader object. The class and internals of this object are
left unspecified.

\standard{add-writer}
\begin{arguments}
  \item[reader] A reader
  \item[class] A class
  \item [type-ident] An identifier ($> 16$)
  \item [function] A function to be called when an object of class
    {\tt class} is encountered.
\end{arguments}
\result
This function adds a new writer function, {\em function} to the given
reader. The function is called when an object of class {\em class} (or
one of its subclasses) is encountered by a write process. It is called
with three arguments: the object to be written, a value representing
write buffer and the reader which called the function. The function
should call {\tt write-next} with any data associated with the object.

\standard{add-reader}
\begin{arguments}
  \item[reader] A reader
  \item [type-ident] An identifier
  \item [function] A function.
\end{arguments}
\result
This function adds a new reader function {\tt function} to the given
reader. The function is called whenever an object of type {\tt
type-ident} is encountered by a read process. It is called with two
arguments: a value representing the read buffer plus
the reader supplied by the caller of the read. The function then calls
{\tt read-next} to obtain any data associated with the object. If the
function fails to consume all the data written by its corresponding
write, an unhandled error condition results\footnote{Feel goes
kaboom}. 

\standard{read-next}
\begin{arguments}
  \item[ptr] A pointer value
  \item [reader] A reader
\end{arguments}
\result
This function returns the next object in the read-buffer specified by
{\em ptr}, using {\em reader} as the reader object. It can only be called
inside the dynamic scope of a read function.

\standard{write-next}
\begin{arguments}
  \item [object] the object to be written
  \item [ptr] A pointer value
  \item [reader] A reader
\end{arguments}
\result
This function writes the object {\em object} onto the write-buffer
specified by ptr, using {\em reader} as the reader object.

\subsection{Example}

\begin{verbatim}
;; define a structure which we want to pass around}

(defstruct silly-cons-pair ()
  ((car initarg car reader silly-car)
   (cdr initarg cdr reader silly-cdr))
  constructor (silly-cons car cdr))

;; invent a number --- this *must* be more than 16
(defconstant *silly-type-id* 18)

;; make a reader

(defconstant *the-reader* (make-obj-reader))

;; define readers and writers for silly-cons

;; note that both these functions *can* side effect, so circular
;; structures and caching can be handled (using tables or similar), also that the
;; particular reader can be changed for the recursive call
;; to the reader (although I do neither here).

(defun write-silly-cons (obj ptr rdr)
  ;; easy really. Just write whats inside.
  (write-next (silly-car obj) ptr rdr)
  (write-next (silly-cdr obj) ptr rdr))

(defun read-silly-cons (ptr rdr)	
  ;; read the internals
  (let* ((a-car (read-next ptr rdr))
         (a-cdr (read-next ptr rdr)))
    ;; construct the appropriate object
    (silly-cons a-car a-cdr)))

;; add them to the reader structure

(add-reader *the-reader*
            *silly-type-id* 
            read-silly-cons)
(add-writer *the-reader*
            silly-cons-pair
            *silly-type-id*
            write-silly-cons)

;; we can add more types later...

;; should make 
;; (pvm-send (pvm-whoami) 102 
;;	     (silly-cons (silly-cons 1 2)
;;                       (silly-cons 3 4))
;;            *the-reader*)
;; work ok.

;; to receive, (pvm-recv 102 nil *the-reader*)
\end{verbatim}

\section{ Bytecode Compiler}
\def\level{Compiler}
The Feel bytecode interpreter is implemented as an add-on to feel,
rather than the integral part of the system that, in an ideal world,
it would be. The code produced is quite respectable, and should give
significant improvements over interpreted code. 

The compiled code does not do any error checking on car, cdr,
vector-ref and similar functions. A later extension will define these
functions as generic so that type errors can be detected. In fact, all
one needs to do is let extras0.em redefine the relevant functions, and
recompile.

\subsection{How to run it}

\subsubsection{File Types}
\begin{description}
\item[Eulisp module files] 
  These have a {\tt .em} suffix and contain eulisp source code. 
\item[Standard compiled modules] 
  These have a {\tt .sc} suffix, and contain position and byte-order
  independent compiled code. 
\item[Interface files] 
  These have a {\tt .i} suffix, and contain the interface exported by
  their module, and information on dependencies, etc.
\item[Bytecode files] 
  These have {\tt .ebc} and {\tt .est} sufficies. They hold the raw
  bytecodes and statics for a group of modules. 
\item[Fast load files]
  These have .fm extensions, and contain raw bytecodes for a single
  module. 
\item[Documentation files]
  These have a .doc extension (probably a bad choice), and contain
  bytefunction names, and their documentation. Note that this is a
  very recent addition to the compiler, but seems simple enough to
  work reliably.
\end{description}

\subsubsection{Compiling}
   The compiler is invoked from inside the compile module. This module
exports the following bindings:

\standard{comp2sc}
\begin{arguments}
  \item [module-name] A symbol
\end{arguments}
\result
Compile a {\tt .em} file into a {\tt .sc} file, plus a {\tt .i} file. 

\standard{(setter optimize-code)}
\begin{arguments}
  \item[value] New value
\end{arguments}
\result
If value is non-nil, then the peephole optimiser will be invoked at
the end of compilations. This reduces code size by an average
10\%, and also makes code execute a little faster. The optimiser
handles most obvious optimisations, but does not attempt any cross
procedure-call/branch optimisations.

\subsubsection{linking}
The linker is invoked from the combine module. It exports the
following bindings:

\standard{load-module}
\begin{arguments}
  \item[module name] A symbol
\end{arguments}
\result
Load a module into the current feel image. It will also load any
submodules that the module needs. For this to work correctly, there
should be no implicit dependencies between the initialisation of
modules --- if (the initialisation of) module A depends on module B,
then A should use a binding from B. For the majority of cases, it
should work OK. 

\standard{load-modules}
\begin{arguments}
  \item[module-list] List of symbols
\end{arguments}
Load all of the modules in mod-list in the given order. 

\standard{combine-user-modules}
\begin{arguments}
  \item [image-name] A symbol
  \item [module-list] List of modules
\end{arguments}
\result
Link the modules in mod-list with the system module standard0,
producing an file which can be used with the -boot option. 

\standard{combine-user-modules-with-desc}
\begin{arguments}
  \item [image-name] A symbol
  \item [module-list] List of modules
  \item[filename] Module-description file
\end{arguments}
\result
As above, but use the description file provided to locate external
bindings, rather than the system itself. This is primarily for
cross-linking. 

\subsubsection{running}
To have feel load an image, {\tt bootimage}, produced by
combine-modules, do: 
\begin{center}
{\tt feel -boot bootimage}
\end{center} 

\subsection{Bootstrapping}

The directory Feel/Boot contains a Makefile. Modify this to fit in
with your system, and do {\tt make map} followed by {\tt make init
map}. This should produce a map of the system, and an initialization
module.  Then, in the directory Feel/Boot/CBoot, edit the Makefile,
and do {\tt make install}. After half an hour or so, an image file
should be produced. To test do ../.../Src/you -boot image. This should
produce a running image. {\tt feel -boot image} should then work on
your system.

%\begin{thefunctionindex}
%\input fun-idx
%\end{thefunctionindex}

%\begin{themoduleindex}
%\input mod-idx
%\end{themoduleindex}

%\begin{theindex}
%\input feel-idx
%\end{theindex}  

\end{document}



\comment{
\appendix

\section{Example of YY and EuLisp}
This section shows the implementation of a small Turtle graphics
kernel, similar to that found in the LOGO language. 

\begin{verbatim}
;; File: turtle.em
;; Date: 11/10/90
;;   Document version
;; Turtle graphics
;; 
;; Provided:
;; make-Turtle-Window:
;;    has initargs server + x-server
;;    these go for the environment if nowhere else 
;;    possible: DISPLAY for the X-server, and YYSERVER for the
;;     	 	name of the machine running the YY server.
;; 
;; make-Turtle
;;  pen-up
;;  pen-down
;;  pen-state
;;  move-forward
;;  move-backward
;;  turn-clock
;;  turn-anticlock
;;  pen-colour
;;   NB: This defaults to black

(defmodule turtle
  ;; scan args is a module containing a single function that 
  ;; looks through an initlist for a gived key and returns the value,
  ;; or a default if  the key is not in the list.

  (standard
   scan-args
   YY
   loops)

  ;; We need somewhere where our turtles can live 

  (defstruct Turtle-Window ()
    ((root-territory accessor Turtle-Window-root-territory)
     (draw-territory accessor Turtle-Window-draw-territory)
     (info-territory accessor Turtle-Window-info-territory)
     (n-turtles initform 0 accessor Turtle-Window-n-turtles))
    constructor make-Turtle-Window)
  
  ;; default window size
  (defconstant *window-size* 500)

  ;; we need to specify this so that we can calculate space for the
  ;; text window
  (defconstant *max-turtles* 5)
  
  ;; magic number  -- degrees to radians
  (defconstant *deg2rad* (/ pi 180))

  ;; the creation of a turtle window needs a little bit of footwork 
  (defmethod initialize-instance ((proto Turtle-Window) init-list)
    (let ((new-turtle-win (call-next-method))
          (server-opt (scan-args 'server
                                 init-list
                                 (getenv "YYSERVER")))
          (x-server-opt (scan-args 'x-server init-list
                                   (getenv "DISPLAY")))
          (size-opt (scan-args 'size init-list
                               *window-size*)))
      ;; initialise if we haven't already
      (cond ((not (YY-initialised-p))
             (YY-connect server-opt 0)
             (initialise-server x-server-opt
                                "Turtle-Graphics"
                                "Turtle-Window")))
      (let ((root-area (make-Area 'left 0 'right size-opt 
                                  'top 0 'bottom (+ (text-size)
                                                    size-opt)))
            (draw-area (make-Area 'left 0 'right size-opt
                                  'top 0 'bottom size-opt))
            (text-area (make-Area 'left 0 'right size-opt
                                  'top size-opt 
                                  'bottom (+ (text-size)
                                             size-opt))))
        ((setter Turtle-Window-root-territory) new-turtle-win
         (make-Territory 'area root-area 'parent nil 'visible t 'drawable nil))
        ((setter Turtle-Window-draw-territory) new-turtle-win
         (make-Territory 'area draw-area
                         'parent (Turtle-Window-root-territory new-turtle-win)
                         'visible t 'drawable t))
        ((setter Turtle-Window-info-territory) new-turtle-win
         (make-Territory 'area text-area 
                         'parent (Turtle-Window-root-territory new-turtle-win)
                         'visible t 'drawable t)))
        new-turtle-win))
  
  ;; move to next id.
  (defun next-turtle-id (tw)
    (++ (Turtle-Window-n-turtles tw))
    (Turtle-Window-n-turtles tw))

  ;; size of text area
  (defun text-size ()
    (* (Font-height (Std-Font)) (+ 1 *max-turtles*)))
  
  ;; give Y cord of where to put text
  (defun locate-turtle-text (id)
    (* (Font-height (Std-Font)) (+ 1 id)))
  
  ;; The turtle itself
  (defstruct Turtle ()
    ((location initform (cons 0 0)
               accessor Turtle-location)
     (direction initform 0
                accessor Turtle-direction)
     (pen-state initform 'DOWN
                accessor Turtle-pen-state)
     (id accessor Turtle-id)
     (colour initform (Black-Colour)
             reader turtle-pen
             writer change-pen
             accessor Turtle-colour)
     (window initarg window
             accessor Turtle-window))
    constructor make-Turtle)

  ;; just need to make sure the id is OK,
  ;; and put the turtle in the middle of the screen
  ;; t1 ignored
  (defmethod initialize-instance ((t1 Turtle) init-list)
    (let ((new-turtle (call-next-method)))
      ((setter Turtle-id) new-turtle
       (next-turtle-id (Turtle-window new-turtle)))
      ((setter Turtle-location) new-turtle
       (cons (/ (Territory-width  (Turtle-Window-draw-territory
			          (Turtle-window new-turtle))) 2)
             (/ (Territory-height (Turtle-Window-draw-territory 
			          (Turtle-window new-turtle))) 2)))
      (show-status new-turtle)
      new-turtle))
  
  ;; printing my status
  (defun show-status (turtle)
    (draw-filled-rectangle-xy (Turtle-Window-info-territory (Turtle-window turtle))
                              0
                              (- (locate-turtle-text (Turtle-id turtle))
                                 (Font-height (Std-Font)))
                              (Territory-width (Turtle-Window-info-territory
                                                (Turtle-window turtle)))
                              (Font-height (Std-Font))
                              GCLEAR (Black-Colour) nil)
    (draw-string-xy (Turtle-Window-info-territory (Turtle-window turtle))
                    0 (locate-turtle-text (Turtle-id turtle))
                    GSET (Turtle-colour turtle) (Std-Font)
                    (format nil "Turtle: ~a Location: ~a Direction: ~a Pen: ~a"
                            (Turtle-id turtle) (Turtle-location turtle)
                            (Turtle-direction turtle) (Turtle-pen-state turtle)))
    nil)

  ;; movement and all that 
  (defun pen-up (turtle)
    ((setter Turtle-pen-state) turtle 'UP)
    (show-status turtle)
    'UP)

  (defun pen-down (turtle)
    ((setter Turtle-pen-state) turtle 'DOWN)
    (show-status turtle)
    'DOWN)
  
  (defun turn-anticlockwise (turtle angle)
    ((setter Turtle-direction) turtle
     (normalise (+ (Turtle-direction turtle) angle) 360))
    (show-status turtle))
     

  (defun turn-clockwise (turtle angle)
    ((setter Turtle-direction) turtle
     (normalise (- (Turtle-direction turtle) direction) 360))
    (show-status turtle))

  (defun move-forward (turtle distance)
    (let ((prev-location (Turtle-location turtle))
          (new-location (sum-points (Turtle-location turtle)
                                    (polar2rect distance
                                                (Turtle-direction turtle)))))
      (cond ((eq (Turtle-pen-state turtle) 'UP)
             nil)
            ((eq (Turtle-pen-state turtle) 'DOWN)
             (draw-line-xy (Turtle-Window-draw-territory (Turtle-window turtle))
                            (car prev-location)
                            (cdr prev-location)
                            (car new-location)
                            (cdr new-location)
                            1 GSET 1 (Turtle-colour turtle) 0))
            (t (error "Duke of york error" Internal-Error 0)))
      ((setter Turtle-location) turtle new-location))
    (show-status turtle))

  ;; do we want the user to know about colours
  (defun make-pen (r g b)
    (make-Colour 'r r 'g g 'b b))

  ;; exports
  (export make-Turtle make-Turtle-Window pen-up pen-down 
          turn-clockwise turn-anticlockwise move-forward
          make-Colour turtle-pen change-pen make-pen)

  ;; utilities
  (defun sum-points (p1 p2)
    (cons (+ (car p1) (car p2))
          (+ (cdr p1) (cdr p2))))

  ;; Darn useful function
  (defun polar2rect (d th)
    (cons (round (* (cos (* th *deg2rad*)) d))
          (round (* (sin (* th *deg2rad*)) d))))
  
  (defun normalise (x y)
    (cond ((> x y) (- x y))
          ((< x (- y)) (+ x y))
          (t x)))
)
\end{verbatim}

}
\end{document}

%% OLD GARBAGE....
\section{Compilation}
A \eulisp\ compiler for \feel\ is under development.  The front-end of
a compiler from modules to Elvira (the opcodes for a \eulisp\
virtual machine) currently comprise seven modules:
\begin{description}
\item[{\tt trandecl}:] defines the data structures used in the
compiler.
\item[{\tt tranutil}:] defines some useful function that are used
in most of the compiler modules.
\item[{\tt cd}:] used by {\tt expand}.
\item[{\tt expand}] exports {\tt macroexpand-body} which takes the
body of a module and carries out macro expansion based on the module's
imported macro definitions.
\item[{\tt makemod}:] exports {\tt make-module-description} which
analyses a whole module, constructing the import and export
information, calling the macro expansion, collects definition
information and writes the initial interface file.
\item[{\tt l02el}:] exports {\tt tran-defmodule} which given a
module descriptor (as constructed by {\tt make-module-descriptor}),
translates all the forms in the body to a sequence of Elvira opcodes,
storing the code in another slot of the module descriptor.
\item[{\tt tran}:] exports {\tt translate-one-module} and {\tt
translate-module}.  The former constructs the module description and
then translates it.  The latter does the same, but also checks on
consistency of imported modules and translates them if source and
interface and object do not have the correct chronological
relationship.
\end{description}
\noindent
This is a relatively simple compiler which generates unremarkable
code.  A further pass, to construct basic blocks and carry out machine
independent optimisations is under development.

\subsection{EuLisp to C}
A back-end from Elvira to C is also under development.  The code is in
the module {\tt el2c}.  The back-end can only handle a subset of
Elvira.  The means to use the translator to C in conjunction with the
front-end is provided by the module {\tt eu2c} which exports {\tt
compile-one-module}.  This function takes a single argument which is a
symbol naming a module.  The file named by the symbol, suffixed with
``{\tt .em}'' is assumed to contain the definition of the module.  A
file named by the symbol, suffixed with ``{\tt .i}'' will be created
to store the interface information, another, suffixed with ``{\tt
.xm}'', to store the expanded definition and another, suffixed with
``{\tt .c}'' to store the generated C code.

New \feel\ systems can be linked incorporating modules compiled to C
code by using the script {\tt ecc} which takes the same arguents as a
C compiler.  For example:

\begin{center}
{\tt ecc -g -o myfeel mymodule1.o mymodule2.c}
\end{center}

builds a new executable image incorporating {\tt mymodule1} and {\tt
mymodule2}.
